/*
 * Created on 2007-12-29
 *
 * TODO 
 */
package jacky.lanlan.song.extension.struts.action;

import jacky.lanlan.song.extension.struts.Scope;

/**
 * 底层 Servlet API 和 Action 之间的间接层，让Action可以不用依赖Servlet API。<br/>
 * 语意类似于 Struts2 的 ValueStack，是Model和View之间传递数据的平台。
 * @author Jacky.Song
 */
public interface ValueStack {

	/**
	 * 把值保存到指定范围。
	 * @param name 属性名
	 * @param value 属性值
	 * @param scope 指定范围
	 */
	void setAttribute(String name, Object value,Scope scope);

	/**
	 * 把属性保存到 <b style="color:red">Request</b>。<br/>
	 * 由于多数时候都在 Request 中保存值，所以提供了这个便利方法。
	 * @param name 属性名
	 * @param value 属性值
	 */
	void setAttribute(String name, Object value);

	/**
	 * 得到指定范围的属性值。
	 * @param name 属性名
	 * @param scope 指定范围
	 */
	Object getAttribute(String name,Scope scope);
	
	/**
	 * 自动在所有范围内搜索属性值：
	 * <p>
	 * 搜索顺序为：<i style="color:red">Request</i> -> <i style="color:red">Session</i>
	 * -> <i style="color:red">ServletContext</i><br/>
	 * 如果在多个范围内存在同名属性，则按照上面的顺序寻找，返回第一次找到的值。
	 * <p>
	 * 比如：在 Request、Session 和 ServletContext 中都有"duplicate"属性，
	 * 则返回 Request 中的那个。
	 * @param name 属性名
	 */
	Object getAttribute(String name);
	
	/**
	 * 删除指定范围的属性。
	 * @param name 属性名
	 * @param scope 指定范围
	 */
	void removeAttribute(String name,Scope scope);

	/**
	 * 得到Request的请求参数。
	 * @param name 参数名
	 * @return 参数值
	 */
	String getRequestParameter(String name);

}
